Scripting Overview

To add custom logic to dataflows, you have two options for scripting:

DGScript

DGScript is a proprietary, JavaScript-based language that provides ready access to Solution Builder data and functions. DGScriptruns in the Solution Builder context, so it does not have the access to outside resources that JavaScript provides. To create scripts using DGScript, add Script blocks to your dataflows.
You also use DGScript in Filter blocks (in the condition property) blocks and Column Mapping blocks (in the from n property).
JavaScript
If your script requires access to resources that reside outside Solution Builder, use JavaScript. JavaScript is faster than DGScript, but if you need access to Solution Builder data and functions, you must manually import the required classes.

For debugging, you can print output to the block's print property or to the browser console, as follows.

Print to the current block's print property: print("<debug output...>");
Print to the browser console: printConsole("<debug output...>");

Example: Injecting Custom Javascript

As an alternative to JavaScript dataflow blocks, you can introduce JavaScript into an application using symbols created from IFrames. The basic workflow is as follows:

Create the desired JavaScript file.
Create an HTML file that includes the JavaScript.
Create an IFrame symbol that includes the HTML, and add properties for JavaScript parameters as required.

The following example enables you to control how text is displayed in an IFrame. The key element in this example is the use of the dgUpdateParams function to push parameter changes to symbol properties. To implement the example, perform the following steps.

Step 1: Create the HTML file

In a test project, add an HTML file containing the code shown below.

<!DOCTYPE html>
<!--  https://github.com/web-animations/web-animations-js -->
<html>
 <body>
   <div class="pulse" style="width:150px;">Hello world!</div>
   <script type='text/javascript' src='dgframe.js'></script>
   <script type='text/javascript'>
        //DEFINE VARIABLES
        var duration = 500;
        var header = "Hello world!";
        var element = document.querySelector(".pulse");
        var animate = {
            direction: "alternate",
            duration: 500,
            iterations: Infinity
        };
        //DEFINE DYNAMIC PROPERTIES
        var dgParams = {
            "duration": function(val) {
                if (typeof(val) == "number") {
                    duration = val;
                }
            },
            "header": function(val) {
                if (typeof(val) == "string") {
                    header = val;
                }
            }
        };
 
        //APPLY TEXT AND ANIMATION TO ELEMENT
        element.textContent = header;
        element.animate([
            {opacity: 0.5, transform: "scale(0.5)"},
            {opacity: 1.0, transform: "scale(1)"}
        ], animate);
 
        //DEFINE ON LOAD SCRIPT
        window.onload = function() {
            //DEFINE REQUEST ANIMATION FRAME FROM BROWSER
            window.requestAnimFrame = (function(){
                return  window.requestAnimationFrame       ||
                        window.webkitRequestAnimationFrame ||
                        window.mozRequestAnimationFrame    ||
                        function (callback) {
                            window.setTimeout(callback, 1000 / 60);
                        };
            })();
 
            //DEFINE WHAT HAPPENS ON LOOP
            function update() {
                if (element.textContent != header) {
                    element.textContent = header;
                }
                if (animate.duration != duration) {
                    animate.duration = duration;
                    element.animate([
                        {opacity: 0.5, transform: "scale(0.5)"},
                        {opacity: 1.0, transform: "scale(1)"}
                    ], animate);
                }
            }
 
            //DEFINE THE LOOP ITSELF
            function loop() {
                requestAnimFrame(loop);
                update();
            }
 
            loop();
        }
   </script>
 </body>
</html>

Step 2: Add the JavaScript File

In the same test project folder where you created the HTML file, add JavaScript file containing the code shown below.

// test if a parameter value is dglux table.
function dgIsParamTable(val){
  return (val != null && typeof(val)=='object' && val.hasOwnProperty('cols') && val.hasOwnProperty('rows'));
}
 
 
// interface to the application
function onDGFrameMessage(e){
  var data = e.data;
  if (typeof(data)=='object'){
    if (data.hasOwnProperty('dgIframeInit')){
      dgIframeId = data['dgIframeInit'];
      if (window.parent != null){
        // the first post back shouldn't contain any data change
        window.parent.postMessage({'dgIframe':dgIframeId},'*');
      }
    } else if (data.hasOwnProperty('dgIframeUpdate')){
      var updates = data['updates'];
      if (typeof(updates)=='object'){
        if (typeof(dgParams) == 'object'){
          for (key in dgParams){
            if (updates.hasOwnProperty(key)){
              dgParams[key](updates[key]);
            }
          }
        }
 
        if (typeof(dgParamsUpdated) == 'function'){
          dgParamsUpdated();
        }
      }
    }
  }
}
window.addEventListener('message',onDGFrameMessage);
 
// push parameter changes back to Solution Builder
function dgUpdateParams(changes) {
  if (dgIframeId != null) {
    window.parent.postMessage({'dgIframe':dgIframeId, changes:changes},'*');
  } else {
    throw 'dgUpdateParams failed, handshake not finished';
  }
}

Step 3: Create the IFrame Symbol

To define the required symbol, perform the following steps.

In Edit mode, drag the HTML file from the project pane to the stage. An IFrame component is created, displaying a size-changing "Hello World" message. Style it for visibility as desired.
Select the IFrame and choose Convert to Symbol. Assign the symbol a name and verify that the new symbol is listed in the Symbols pane, then delete it from the Stage.
In the Symbols pane, right-click the new symbol and choose Edit. The symbol editing dialog is displayed.
Choose Modify > Edit Properties. The Symbol Parameters dialog is displayed.
Add two parameters:
- duration: number
- header: string
Click Apply, then click OK to dismiss the dialog.

To verify that changes to the symbol properties are passed to the JavaScript that controls the appearance of the text displayed in the IFrame, add an instance of the symbol to the Stage. To change the rate at which the text moves, set its duration property. To change the text itself, set its header property.